home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / StringCharacterIterator.java < prev    next >
Text File  |  1998-09-22  |  9KB  |  297 lines
  1. /*
  2.  * @(#)StringCharacterIterator.java    1.15 98/02/02
  3.  *
  4.  * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
  5.  * (C) Copyright IBM Corp. 1996 - All Rights Reserved
  6.  *
  7.  * Portions copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
  8.  *
  9.  *   The original version of this source code and documentation is copyrighted
  10.  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
  11.  * materials are provided under terms of a License Agreement between Taligent
  12.  * and Sun. This technology is protected by multiple US and International
  13.  * patents. This notice and attribution to Taligent may not be removed.
  14.  *   Taligent is a registered trademark of Taligent, Inc.
  15.  *
  16.  * Permission to use, copy, modify, and distribute this software
  17.  * and its documentation for NON-COMMERCIAL purposes and without
  18.  * fee is hereby granted provided that this copyright notice
  19.  * appears in all copies. Please refer to the file "copyright.html"
  20.  * for further important copyright and licensing information.
  21.  *
  22.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  23.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  24.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  25.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  26.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  27.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  28.  *
  29.  */
  30.  
  31. package java.text;
  32.  
  33. /**
  34.  * <code>StringCharacterIterator</code> implements the
  35.  * <code>CharacterIterater</code> protocol for a <code>String</code>.
  36.  * The <code>StringCharacterIterator</code> class iterates over the
  37.  * entire <code>String</code>.
  38.  *
  39.  * <P>
  40.  * <strong>Examples</strong>:
  41.  *
  42.  * <P>
  43.  * Traverse the text from start to finish
  44.  * <blockquote>
  45.  * <pre>
  46.  * public void traverseForward(CharacterIterator iter) {
  47.  *     for (char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
  48.  *         processChar(c);
  49.  *     }
  50.  * }
  51.  * </pre>
  52.  * </blockquote>
  53.  * Traverse the text backwards, from end to start
  54.  * <blockquote>
  55.  * <pre>
  56.  * public void traverseBackward(CharacterIterator iter) {
  57.  *     for (char c = iter.last(); c != CharacterIterator.DONE; c = iter.prev()) {
  58.  *         processChar(c);
  59.  *     }
  60.  * }
  61.  * </pre>
  62.  * </blockquote>
  63.  *
  64.  * Traverse both forward and backward from a given position in the text.
  65.  * <blockquote>
  66.  * <pre>
  67.  * public void traverseOut(CharacterIterator iter, int pos) {
  68.  *     for (char c = iter.setIndex(pos);
  69.  *          c != CharacterIterator.DONE && notBoundary(c);
  70.  *          c = iter.next()) {}
  71.  *     int end = iter.getIndex();
  72.  *     for (char c = iter.setIndex(pos);
  73.  *          c != CharacterIterator.DONE && notBoundary(c);
  74.  *          c = iter.prev()) {}
  75.  *     int start = iter.getIndex();
  76.  *     processSection(iter.getText.subString(start,end);
  77.  * }
  78.  * </pre>
  79.  * </blockquote>
  80.  */
  81.  
  82. public final class StringCharacterIterator implements CharacterIterator
  83. {
  84.     private String text;
  85.     private int begin;
  86.     private int end;
  87.     private int pos;
  88.  
  89.     /**
  90.      * Construct an iterator with an initial index of 0.
  91.      */
  92.     public StringCharacterIterator(String text)
  93.     {
  94.         this(text, 0);
  95.     }
  96.  
  97.     /**
  98.      * Construct an iterator with the specified initial index.
  99.      *
  100.      * @param  text   The String to be iterated over
  101.      * @param  pos    Initial iterator position
  102.      */
  103.     public StringCharacterIterator(String text, int pos)
  104.     {
  105.     this(text, 0, text.length(), pos);
  106.     }
  107.  
  108.     /**
  109.      * Construct an iterator over the given range of the given string, with the
  110.      * index set at the specified position.
  111.      *
  112.      * @param  text   The String to be iterated over
  113.      * @param  begin  Index of the first character
  114.      * @param  end    Index of the character following the last character
  115.      * @param  pos    Initial iterator position
  116.      */
  117.     public StringCharacterIterator(String text, int begin, int end, int pos) {
  118.         if (text == null)
  119.             throw new NullPointerException();
  120.         this.text = text;
  121.  
  122.     if (begin < 0 || begin > end || end > text.length())
  123.         throw new IllegalArgumentException("Invalid substring range");
  124.  
  125.         if (pos < begin || pos > end)
  126.             throw new IllegalArgumentException("Invalid position");
  127.  
  128.         this.begin = begin;
  129.         this.end = end;
  130.         this.pos = pos;
  131.     }
  132.  
  133.  
  134.     /**
  135.      * Set the position to getBeginIndex() and return the character at that
  136.      * position.
  137.      */
  138.     public char first()
  139.     {
  140.         pos = begin;
  141.         return text.charAt(pos);
  142.     }
  143.  
  144.     /**
  145.      * Set the position to getEndIndex() and return the
  146.      * character at that position.
  147.      */
  148.     public char last()
  149.     {
  150.         pos = end - 1;
  151.         return text.charAt(pos);
  152.     }
  153.  
  154.     /**
  155.      * Set the position to specified position in the text and return that
  156.      * character.
  157.      */
  158.     public char setIndex(int p)
  159.     {
  160.     if (p < begin || p >= end)
  161.             throw new IllegalArgumentException("Invalid index");
  162.         pos = p;
  163.         return text.charAt(p);
  164.     }
  165.  
  166.     /**
  167.      * Get the character at the current position (as returned by getIndex()).
  168.      * @return the character at the current position or DONE if the current
  169.      * position is off the end of the text.
  170.      */
  171.     public char current()
  172.     {
  173.         if (pos >= begin && pos < end) {
  174.             return text.charAt(pos);
  175.         }
  176.         else {
  177.             return DONE;
  178.         }
  179.     }
  180.  
  181.     /**
  182.      * Increment the iterator's index by one and return the character
  183.      * at the new index.  If the resulting index is greater or equal
  184.      * to getEndIndex(), the current index is reset to getEndIndex() and
  185.      * a value of DONE is returned.
  186.      * @return the character at the new position or DONE if the current
  187.      * position is off the end of the text.
  188.      */
  189.     public char next()
  190.     {
  191.         if (pos < end - 1) {
  192.             pos++;
  193.             return text.charAt(pos);
  194.         }
  195.         else {
  196.             pos = end;
  197.             return DONE;
  198.         }
  199.     }
  200.  
  201.     /**
  202.      * Decrement the iterator's index by one and return the character
  203.      * at the new index.  If the resulting index is
  204.      * less than getBeginIndex(), the current index is reset to getBeginIndex()
  205.      * and a value of DONE is returned.
  206.      * @return the character at the new position or DONE if the current
  207.      * position is off the end of the text.
  208.      */
  209.     public char previous()
  210.     {
  211.         if (pos > begin) {
  212.             return text.charAt(--pos);
  213.         }
  214.         else {
  215.             return DONE;
  216.         }
  217.     }
  218.  
  219.     /**
  220.      * Return the start index of the text.
  221.      * @return the index at which the text begins.
  222.      */
  223.     public int getBeginIndex()
  224.     {
  225.         return begin;
  226.     }
  227.  
  228.     /**
  229.      * Return the end index of the text.  This index is the index of the
  230.      * first character following the end of the text.
  231.      * @return the index at which the text end.
  232.      */
  233.     public int getEndIndex()
  234.     {
  235.         return end;
  236.     }
  237.  
  238.     /**
  239.      * Return the current index.
  240.      * @return the current index.
  241.      */
  242.     public int getIndex()
  243.     {
  244.         return pos;
  245.     }
  246.  
  247.     /**
  248.      * Compares the equality of two StringCharacterIterator objects.
  249.      * @param obj the StringCharacterIterator object to be compared with.
  250.      * @return true if the given obj is the same as this
  251.      * StringCharacterIterator object; false otherwise.
  252.      */
  253.     public boolean equals(Object obj)
  254.     {
  255.         if (this == obj)
  256.             return true;
  257.         if (!(obj instanceof StringCharacterIterator))
  258.             return false;
  259.  
  260.         StringCharacterIterator that = (StringCharacterIterator) obj;
  261.  
  262.         if (hashCode() != that.hashCode())
  263.             return false;
  264.         if (!text.equals(that.text))
  265.             return false;
  266.         if (pos != that.pos || begin != that.begin || end != that.end)
  267.             return false;
  268.         return true;
  269.     }
  270.  
  271.     /**
  272.      * Compute a hashcode for this enumeration
  273.      * @return A hash code
  274.      */
  275.     public int hashCode()
  276.     {
  277.         return text.hashCode() ^ pos ^ begin ^ end;
  278.     }
  279.  
  280.     /**
  281.      * Create a copy of this boundary
  282.      * @return A copy of this
  283.      */
  284.     public Object clone()
  285.     {
  286.         try {
  287.             StringCharacterIterator other
  288.             = (StringCharacterIterator) super.clone();
  289.             return other;
  290.         }
  291.         catch (CloneNotSupportedException e) {
  292.             throw new InternalError();
  293.         }
  294.     }
  295.  
  296. }
  297.